home *** CD-ROM | disk | FTP | other *** search
/ OctaMED Sound Studio 1 / OctaMED SoundStudio V1.iso / soundstudio v1 / programmers / library.doc < prev    next >
Text File  |  1996-06-18  |  15KB  |  525 lines
  1. ***************************************************************************
  2.  
  3. Instructions for using "medplayer.library", "octaplayer.library" and
  4. "octamixplayer.library" V7.0.
  5.  
  6. ***************************************************************************
  7.  
  8.  
  9.         medplayer.library
  10.         ~~~~~~~~~~~~~~~~~
  11.  
  12. "medplayer.library" is a shared library, which can be used to load and play
  13. MED/OctaMED  4-channel modules You can call its functions from any language
  14. which supports library calls (C, Assembler, Basic...)
  15.  
  16. "medplayer.library" supports only 4-channel MED songs. For OctaMED 5 - 8
  17. channel songs, you must use octaplayer.library. "octamixplayer.library" is
  18. provided for OctaMED Soundstudio songs that use the mixing routine.
  19.  
  20. There's a header file 'libproto.h' that contains the prototypes and
  21. #pragmas of all three libraries for use with SAS/C.
  22.  
  23. Here's the complete list of the functions in "medplayer.library" (in RKM
  24. autodoc-style):
  25.  
  26. ---------------------------------------------------------------------------
  27. ---------------------------------------------------------------------------
  28.  
  29. GetPlayer
  30.  
  31. NAME
  32.     GetPlayer -- get and initialize the player routine
  33.  
  34. SYNOPSIS
  35.     error = GetPlayer(midi)
  36.     D0                D0
  37.  
  38. FUNCTION
  39.     This routine allocates the audio channels and CIAB timer A/B
  40.     and prepares the interrupt. If "midi" is nonzero, serial
  41.     port is allocated and initialized. You should call this
  42.     routine when your programs starts up.
  43.  
  44. INPUTS
  45.     midi =  0 no midi, 1 set up midi. When you use a song that
  46.         has only Amiga samples, there's no reason to allocate
  47.         the serial port. Then set midi to 0.
  48.  
  49. RESULT
  50.     If everything is OK, GetPlayer() returns zero. If initialization
  51.     failed or somebody else is currently using the library, then
  52.     GetPlayer() returns nonzero value.
  53.     NOTE: Even if GetPlayer() returned an error, you can still call
  54.           the library functions without making harm. They just won't
  55.           work (except LoadModule(), UnLoadModule(), RelocModule()
  56.           and GetCurrentModule(), which always work).
  57.  
  58. SEE ALSO
  59.     FreePlayer
  60.  
  61. ---------------------------------------------------------------------------
  62. ---------------------------------------------------------------------------
  63.  
  64. FreePlayer
  65.  
  66. NAME
  67.     FreePlayer -- free the resources allocated by GetPlayer()
  68.  
  69. SYNOPSIS
  70.     FreePlayer()
  71.  
  72. FUNCTION
  73.     This routine frees all resources allocated by GetPlayer().
  74.     Remember always call this routine before your program
  75.     exits. It doesn't harm to call this if GetPlayer() failed.
  76.     If you don't call this function during exit, audio channels,
  77.     timer etc. will remain allocated until reboot.
  78.  
  79. SEE ALSO
  80.     GetPlayer
  81.  
  82. ---------------------------------------------------------------------------
  83. ---------------------------------------------------------------------------
  84.  
  85. PlayModule
  86.  
  87. NAME
  88.     PlayModule -- play module from the beginning
  89.  
  90. SYNOPSIS
  91.     PlayModule(module)
  92.                A0
  93.  
  94. FUNCTION
  95.     This routine starts to play the module from the beginning.
  96.     The module can be obtained by calling LoadModule() or it can
  97.     be incorporated directly into your program. The module has to
  98.     be relocated before calling PlayModule()!
  99.  
  100. INPUTS
  101.     module = pointer to the module.
  102.  
  103. SEE ALSO
  104.     ContModule, StopPlayer
  105.  
  106. ---------------------------------------------------------------------------
  107. ---------------------------------------------------------------------------
  108.  
  109. ContModule
  110.  
  111. NAME
  112.     ContModule -- continue playing the module from where it stopped
  113.  
  114. SYNOPSIS
  115.     ContModule(module)
  116.                A0
  117.  
  118. FUNCTION
  119.     ContModule() functions just like PlayModule() except if you
  120.     have stopped playing with StopPlayer(), the playing will
  121.     continue where it stopped. When you play the module first
  122.     time, you should use PlayModule().
  123.  
  124. INPUTS
  125.     module = pointer to module.
  126.  
  127. SEE ALSO
  128.     PlayModule, StopPlayer
  129.  
  130. ---------------------------------------------------------------------------
  131. ---------------------------------------------------------------------------
  132.  
  133. StopPlayer
  134.  
  135. NAME
  136.     StopPlayer -- stops playing immediately
  137.  
  138. SYNOPSIS
  139.     StopPlayer()
  140.  
  141. FUNCTION
  142.     Stop.
  143.  
  144. SEE ALSO
  145.     PlayModule, ContModule
  146.  
  147. ---------------------------------------------------------------------------
  148. ---------------------------------------------------------------------------
  149.  
  150. DimOffPlayer
  151.  
  152. NOTE
  153.     This is an obsolete function! It was removed in V2 of the library,
  154.     and it now just does StopPlayer()!
  155.  
  156. ---------------------------------------------------------------------------
  157. ---------------------------------------------------------------------------
  158.  
  159. SetTempo
  160.  
  161. NAME
  162.     SetTempo -- modify the playing speed
  163.  
  164. SYNOPSIS
  165.     SetTempo(tempo)
  166.              D0
  167.  
  168. FUNCTION
  169.     If you want to modify the playback speed, you can call this one.
  170.     This number should be 1 - 240. Note that tempos 1 - 10 are
  171.     recognized as SoundTracker tempos. This function probably has not
  172.     much use.
  173.  
  174. INPUTS
  175.     tempo = new tempo
  176.  
  177. ---------------------------------------------------------------------------
  178. ---------------------------------------------------------------------------
  179.  
  180. LoadModule
  181.  
  182. NAME
  183.     LoadModule -- load a MED module from disk and relocate it
  184.  
  185. SYNOPSIS
  186.     module = LoadModule(name)
  187.     D0                  A0
  188.  
  189. FUNCTION
  190.     When you want to load a module from disk, call this function.
  191.     The function loads only MED modules (MMD0). It doesn't load
  192.     Tracker-modules, MED songs or object files. Only MMD0's
  193.     (MMD0 is the identification word at the beginning of the file).
  194.     Because the module contains many pointers, they must be
  195.     relocated. This function relocates the module automatically.
  196.     If you include the module as a binary file converted with
  197.     Objconv, YOU must relocate it. This is an easy thing to do.
  198.     Just call RelocModule().
  199.  
  200.     Medplayer.library version 3 and later also handle OctaMED Pro
  201.     MMD1 modules. Versions 5 and above handle MMD2 modules as well.
  202.  
  203. INPUTS
  204.     name = pointer to file name (null-terminated)
  205.  
  206. RESULT
  207.     module = pointer to module. If failed to load for some reason
  208.              (disk error, out of memory, not a module), zero will
  209.           be returned.
  210.  
  211. SEE ALSO
  212.     UnLoadModule
  213.  
  214. ---------------------------------------------------------------------------
  215. ---------------------------------------------------------------------------
  216.  
  217. UnLoadModule
  218.  
  219. NAME
  220.     UnLoadModule -- frees the module from memory
  221.  
  222. SYNOPSIS
  223.     UnLoadModule(module)
  224.                  A0
  225. FUNCTION
  226.     When you don't need the module anymore, you MUST free the
  227.     memory it has used. Use this routine for it. Remember to
  228.     stop the player before unloading the module it is playing.
  229.  
  230.     NOTE: unload only those modules which are loaded with
  231.     LoadModule(). If you attempt to free module which is a part
  232.     of the program, you will get a guru (81000009/81000005).
  233.  
  234. INPUTS
  235.     module = pointer to module. If zero, nothing happens.
  236.  
  237. SEE ALSO
  238.     LoadModule
  239.  
  240. ---------------------------------------------------------------------------
  241. ---------------------------------------------------------------------------
  242.  
  243. GetCurrentModule
  244.  
  245. NAME
  246.     GetCurrentModule -- returns the address of module currently playing
  247.  
  248. SYNOPSIS
  249.     module = GetCurrentModule()
  250.     D0
  251.  
  252. FUNCTION
  253.     Simply returns the pointer of the module, which is currently
  254.     playing (or if player is stopped, which was played last). This
  255.     works also if some other task is currently playing. In this case,
  256.     because of multitasking, you should have no use for the value
  257.     (the module can be already unloaded). You may ask what use this
  258.     function has. Well, I'm not sure, but because this function
  259.     takes only 2 machine language instructions (8 bytes of memory)
  260.     there's not much harm of it.
  261.  
  262. RESULT
  263.     module = pointer to current module
  264.  
  265. ---------------------------------------------------------------------------
  266. ---------------------------------------------------------------------------
  267.  
  268. ResetMIDI
  269.  
  270. NAME
  271.     ResetMIDI -- reset all pitchbenders and modulation wheels and
  272.                  ask player to resend the preset values
  273.  
  274. SYNOPSIS
  275.     ResetMIDI()
  276.  
  277. FUNCTION
  278.     This function resets pitchbenders and modulation wheels on all
  279.     MIDI channels. It also asks the player to send again the
  280.     preset change requests for all instruments, so that the presets
  281.     will be correct if the user has changed them. It performs the
  282.     same function as Ctrl-Space in OctaMED.
  283.  
  284. ---------------------------------------------------------------------------
  285. ---------------------------------------------------------------------------
  286. Note: The following functions are only available in medplayer.library V2
  287. or later, be sure that you're really using V2 of the library
  288. e.g.  MEDPlayerBase = OpenLibrary("medplayer.library",2);
  289. ---------------------------------------------------------------------------
  290. ---------------------------------------------------------------------------
  291.  
  292. SetModnum
  293.  
  294. NAME
  295.     SetModnum -- select the number of the song (in multi-module)
  296.  
  297. SYNOPSIS
  298.     SetModnum(modnum)
  299.           D0
  300.  
  301. FUNCTION
  302.     Use this function to set the number of song you want to play.
  303.     Call this before PlayModule(). 0 is the first song, 1 is the
  304.     second, and so on. If the module is not a multi-module, this
  305.     function has no effect.
  306.  
  307. ---------------------------------------------------------------------------
  308. ---------------------------------------------------------------------------
  309.  
  310. RelocModule
  311.  
  312. NAME
  313.     RelocModule -- relocate module
  314.  
  315. SYNOPSIS
  316.     RelocModule(module)
  317.             A0
  318.  
  319. FUNCTION
  320.     This function relocates the module. It should be used if you've
  321.     incorporated the module with Objconv program before using the
  322.     module. Note that LoadModule() automatically relocs everything.
  323.  
  324. ---------------------------------------------------------------------------
  325. ---------------------------------------------------------------------------
  326. Note: The following functions are only available in medplayer.library V7
  327. or later, be sure that you're really using V7 of the library
  328. e.g.  MEDPlayerBase = OpenLibrary("medplayer.library",7);
  329. ---------------------------------------------------------------------------
  330. ---------------------------------------------------------------------------
  331.  
  332. RequiredPlayRoutine
  333.  
  334. NAME
  335.     RequiredPlayRoutine -- tell which playing routine this mod needs
  336.  
  337. SYNOPSIS
  338.     routine = RequiredPlayRoutine(module)
  339.     D0                A0
  340.  
  341. FUNCTION
  342.     Returns the number of the playing routine (and therefore playing
  343.     library) which is required for correctly replaying the module.
  344.  
  345. RESULT
  346.     0 = normal four channel routine (medplayer.library)
  347.     1 = 5-8 channel routine (octaplayer.library)
  348.     2 = 1-64 channel mixing routine (octamixplayer.library)
  349.     Other values are reserved for the future. You shouldn't do
  350.     anything with the module if any other value is returned.
  351.  
  352. ---------------------------------------------------------------------------
  353. ---------------------------------------------------------------------------
  354.  
  355. FastMemPlayRecommended
  356.  
  357. NAME
  358.     FastMemPlayRecommended -- does the module require fast mem playing?
  359.  
  360. SYNOPSIS
  361.     result = FastMemPlayRecommended(module)
  362.     D0                A0
  363.  
  364. FUNCTION
  365.     Tells if the module uses some of the goodies (long samples and/or
  366.     odd repeat values) that are only available with FastMem playing.
  367.     It's up to you to activate FastMem playing.
  368.  
  369. RESULT
  370.     0 = doesn't require FastMem playing
  371.     1 = does require it
  372.  
  373. SEE ALSO
  374.     SetFastMemPlay()
  375.  
  376. ---------------------------------------------------------------------------
  377. ---------------------------------------------------------------------------
  378.  
  379. LoadModule_Fast
  380.  
  381. NAME
  382.     LoadModule_Fast -- load a module from disk into Fast RAM
  383.  
  384. SYNOPSIS
  385.     module = LoadModule_Fast(module)
  386.     D0             A0
  387.  
  388. FUNCTION
  389.     Loads a module into Fast RAM. Otherwise identical to LoadModule().
  390.  
  391. RESULT
  392.     module = pointer to the loaded module
  393.  
  394. SEE ALSO
  395.     LoadModule()
  396.  
  397. ---------------------------------------------------------------------------
  398. ---------------------------------------------------------------------------
  399.  
  400. SetFastMemPlay
  401.  
  402. NAME
  403.     SetFastMemPlay -- activates/deactivates Fast RAM playing
  404.  
  405. SYNOPSIS
  406.     SetFastMemPlay(newstate,buffsize)
  407.             D0     D1
  408.  
  409. FUNCTION
  410.     Enables or disables Fast RAM playing, and sets the size of the
  411.     output buffer. This routine should only be called when playing
  412.     is stopped.
  413.  
  414. INPUT
  415.     newstate = New state of Fast RAM playing mode (i.e. 1 or 0)
  416.     buffsize = Size of the output buffer, must be between 4 and 400,
  417.            and divisible by four. Use 0 if you want to retain the
  418.            old value
  419.  
  420. SEE ALSO
  421.     FastMemPlayRecommended()
  422.  
  423. ***************************************************************************
  424.  
  425.         octaplayer.library
  426.         ~~~~~~~~~~~~~~~~~~
  427.  
  428. This library is made for playing OctaMED 5 - 8 channel songs ONLY. It does
  429. not support MIDI or 4-channel songs. The functions in it are analogous to
  430. functions in medplayer.library. (See the medplayer.library docs above for
  431. explanation of their usage.)
  432.  
  433. The functions are:
  434.  
  435.     GetPlayer8()        (midi switch ignored)
  436.     FreePlayer8()
  437.     PlayModule8(module)
  438.     ContModule8(module)
  439.     StopPlayer8()
  440.     LoadModule8(filename)
  441.     UnLoadModule8(module)
  442.     SetModnum8(modnum)
  443.     RelocModule8(module)
  444.     RequiredPlayRoutine8(module)
  445.     FastMemPlayRecommended8(module)
  446.     LoadModule_Fast8(module)
  447.     SetFastMemPlay8(newstate,buffsize)
  448.  
  449. As you can see, every function has '8' in its name, and some functions that
  450. are in medplayer.library don't exist. There's also an additional function
  451. that exists only in octaplayer.library (V6 and above):
  452.  
  453. ---------------------------------------------------------------------------
  454.  
  455. SetHQ
  456.  
  457. NAME
  458.     SetHQ - set high quality mode        (V6)
  459.  
  460. SYNOPSIS
  461.     SetHQ(hq)
  462.           D0
  463.  
  464. FUNCTION
  465.     When you allocate the player with GetPlayer8(), the HQ mode is set
  466.     off by default. This function switches the HQ mode on or off.
  467.     (D0: nonzero = on, zero = off).
  468.  
  469.     Note: The player should be stopped when calling this.
  470.  
  471.     Also note: No check is made whether the computer is fast enough to
  472.     handle HQ properly.
  473.  
  474. ---------------------------------------------------------------------------
  475.  
  476. ***************************************************************************
  477. Note:
  478. ~~~~~
  479. Version 3 of both medplayer.library and octaplayer.library handle the new
  480. MMD1 module type correctly. No changes are required to programs calling
  481. these libraries. If you absolutely want MMD1 support, be sure to request
  482. V3 of the libraries.
  483.  
  484. (e.g. OpenLibrary("medplayer.library",3); )
  485.  
  486. As well, if you want MMD2 support, be sure to ask version 5 or later.
  487.  
  488. ***************************************************************************
  489.  
  490.         octamixplayer.library
  491.         ~~~~~~~~~~~~~~~~~~~~~
  492.  
  493. This library is for playing OctaMED Soundstudio modules which utilize the
  494. mixing mode (with 1-64 channels). These functions in octamixplayer.library
  495. are identical (in functionality) to routines in the above two libraries:
  496.  
  497.     GetPlayerM()        (midi switch ignored)
  498.     FreePlayerM()
  499.     PlayModuleM(module)    (see note below!)
  500.     ContModuleM(module)
  501.     StopPlayerM()
  502.     LoadModule_FastM(filename) (loading to chip mem is unnecessary)
  503.     UnLoadModuleM(module)
  504.     SetModnumM(modnum)
  505.     RelocModuleM(module)
  506.     RequiredPlayRoutineM(module)
  507.  
  508. Note that PlayModuleM() may fail (probably because out of memory), and it
  509. returns a non-zero value if it does.
  510.  
  511. These functions control the settings of the mixing routine. They should be
  512. called only when playing is stopped:
  513.  
  514.                 Acceptable values    Default value
  515. Set14BitMode(newmode)        0 or 1 (*)        1
  516. SetMixingFrequency(newfreq)    1000 - 65535 (**)    15000
  517. SetMixBufferSize(newbuffsize)    4 - 32764 (***)        1024
  518.  
  519. *  The sound is louder (but more noisy) if 14-bit mode is turned off.
  520.  
  521. ** Note that the maximum usable mixing frequency depends on the screen mode.
  522.    The highest value that works in the standard 50 Hz modes is about 28800.
  523.  
  524. *** The default value is suitable for most applications.
  525.